Overview

This PR introduces v2.0 of @kaliber/firebase-queue with breaking changes and significant improvements driven by real-world usage analysis.

Why These Changes?

Usage Analysis

Analyzed 7 projects and 18 services:

Code Quality Issues

The original codebase had several code smells:

• Inconsistent patterns: Mix of pseudo-classes, factory functions, and module patterns
• Pseudo-class oddity: Queue used new keyword but was not a real constructor (no this, weird instanceof check)
• No types: Zero TypeScript or JSDoc type annotations
• Large functions: process() was 155 lines with 6 nested functions

Feature Gap vs BullMQ

Breaking Changes ⚠️

Factory functions instead of constructors:

-const Queue = require('@kaliber/firebase-queue')
-const queue = new Queue({ ... })

+const { createQueue } = require('@kaliber/firebase-queue')
+const queue = createQueue({ ... })

Rationale: The old new Queue() pattern was a pseudo-class that did not actually use this - it was a factory function pretending to be a constructor. Converting to explicit factory functions makes the code honest and consistent.

New Features ✨

🔴 P0: Retry with Backoff

Previously manually implemented in rabobank-jobs (~50 lines)

options: {
  retry: {
    maxAttempts: 5,
    backoff: 'exponential', // or 'linear', 'fixed', custom fn
    initialDelayMs: 1000,
    maxDelayMs: 3600000,
    retryableErrors: (error) => error.code !== 'PERMANENT'
  }
}

🟡 P1: Pause/Resume

Previously manually implemented in synchronization-service

queue.pause()    // Stop processing new tasks
queue.resume()   // Continue processing
queue.isPaused() // Check state

Observability

options: {
  observability: {
    logger: winston,      // Structured logging
    metrics: prometheus,  // Counters, histograms, gauges
    tracer: opentelemetry // Distributed tracing
  }
}

Lifecycle Hooks

options: {
  lifecycle: {
    onTaskClaimed: (taskId, workerId) => {},
    onTaskCompleted: (taskId, durationMs, result) => {},
    onTaskFailed: (taskId, durationMs, error) => {},
    onTaskRetryScheduled: (taskId, attempt, delayMs, error) => {},
    onQueuePaused: () => {},
    onQueueResumed: () => {}
  }
}

Queue Stats

queue.getStats()
// { numWorkers, busyWorkers, totalProcessed, totalFailed, totalRetried, isPaused }

Code Quality Improvements

• ✅ Consistent factory pattern throughout (no more pseudo-classes)
• ✅ Comprehensive JSDoc type annotations on all functions
• ✅ Extended types.ts with 50+ type definitions
• ✅ Extracted helpers to task_helpers.js (smaller, focused functions)
• ✅ Merged pnpm branch (Firebase emulator tests, pnpm, eslint)

Testing

pnpm test  # Requires Java for Firebase emulator